import { Meta, Source } from '@storybook/blocks';

<Meta title="INTRODUCTION/Getting Started" />

# Overview
The [@hakit/core](https://www.npmjs.com/package/@hakit/core) uses the official [Home Assistant Web Socket](https://github.com/home-assistant/home-assistant-js-websocket) to provide all the core functionality to authenticate with Home Assistant to create a dynamic dashboard with React!

There's also reusable components for creating custom dashboards for Home Assistant using react, this is a separate package to [@hakit/components](https://www.npmjs.com/package/@hakit/components).

## Prerequisites

Before you begin, ensure you have met the following requirements:
- **Node.js** version 18 or higher. If you do not have Node.js installed, you can download it from the [official Node.js website](https://nodejs.org/).
- **npm** version 7 or higher. npm is distributed with Node.js - when you download Node.js, you automatically get npm installed on your computer.
- **hassToken** technically not required, but recommended you create a <a href="https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token" target="_blank">Long Lived Access Token</a> to provide to `HassConnect`. You can create one in your home assistant instance at the bottom of your profile page.


## Automated Setup Steps
There's an npm create command which will setup react, typescript, vite & hakit automatically for you with a terminal wizard!

<Source dark code={`npm create hakit@latest`} />

***Note: Remember to update the `.env` file with your home assistant url and token.***

Once setup you can ignore everything else on this page and start developing!

## Manual Installation Steps
Install the [@hakit/core](https://www.npmjs.com/package/@hakit/core) for all authentication and react hooks, this is the all the core functionality you'll need, if you want to use some of the components I've built, also install [@hakit/components](https://www.npmjs.com/package/@hakit/components):

<Source dark code={`npm i @hakit/core @hakit/components -D`} />
***Note: This package uses peerDependencies, npm version 4-6 will not install these automatically, you will need to install them [manually](https://stackoverflow.com/questions/35207380/how-to-install-npm-peer-dependencies-automatically), npm version 7 and above will handle this automatically.***


### Sync typescript
There's an awesome subfeature of this package that will generate types specific to your home assistant instance! It's recommended that you [follow this flow](/docs/introduction-typescriptsync--docs)!

### Authenticate

In your root component of your react aplication (usally App.tsx) wrap everything with the [HassConnect](/docs/components-hassconnect--docs) component, don't forget to include the `ThemeProvider` to get the default theme if you're using [@hakit/components](https://www.npmjs.com/package/@hakit/components).

<Source dark code={`
import React from 'react';
import { createRoot } from 'react-dom/client';
import { HassConnect } from '@hakit/core';
import { ThemeProvider } from '@hakit/components';
// TODO: replace this with your home assistant url & token, recommended you place these in a .env file if you're deploying to github.
const HASS_URL = 'http://localhost:8123';
const HASS_TOKEN = 'YOUR_TOKEN_HERE';
function App() {
  return <HassConnect hassUrl={HASS_URL} hassToken={HASS_TOKEN}>
    <ThemeProvider includeThemeControls />
    <p>This will render when connected!</p>
  </HassConnect>
}

const root = createRoot(document.getElementById('root'));

root.render(<App />);
`} />


That's it! Now you can use all the other functionality such as [useService()](/docs/hooks-useservice--docs)! Happy developing :D 


### Deploying to Home Assitant
Once you're happy with your new dashboard, you can follow the steps to [deploy here](/?path=/docs/introduction-deploying--docs) which will guide you through the process of deploying your dashboard to Home Assistant!